From 8de0a2c7c61285123fa918409df233bf954fcffa Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Fri, 19 Feb 2021 16:01:07 -0500 Subject: [PATCH] infobar: Convert docs Change link syntax, add an example image, generally clean things up. --- gtk/gtkinfobar.c | 182 ++++++++++++++++++++++++++--------------------- 1 file changed, 102 insertions(+), 80 deletions(-) diff --git a/gtk/gtkinfobar.c b/gtk/gtkinfobar.c index 608c6b77ff..8213acf5ce 100644 --- a/gtk/gtkinfobar.c +++ b/gtk/gtkinfobar.c @@ -53,27 +53,30 @@ * @include: gtk/gtk.h * @see_also: #GtkStatusbar, #GtkMessageDialog * - * #GtkInfoBar is a widget that can be used to show messages to - * the user without showing a dialog. It is often temporarily shown - * at the top or bottom of a document. In contrast to #GtkDialog, which - * has an action area at the bottom, #GtkInfoBar has an action area - * at the side. + * `GtkInfoBar` is a widget that can be used to show messages to + * the user without showing a dialog. * - * The API of #GtkInfoBar is very similar to #GtkDialog, allowing you - * to add buttons to the action area with gtk_info_bar_add_button() or - * gtk_info_bar_new_with_buttons(). The sensitivity of action widgets - * can be controlled with gtk_info_bar_set_response_sensitive(). + * ![An example GtkInfoBar](infobar.png) * - * To add widgets to the main content area of a #GtkInfoBar, use - * gtk_info_bar_add_child(). + * It is often temporarily shown at the top or bottom of a document. + * In contrast to [class@Gtk.Dialog], which has an action area at the + * bottom, `GtkInfoBar` has an action area at the side. * - * Similar to #GtkMessageDialog, the contents of a #GtkInfoBar can by - * classified as error message, warning, informational message, etc, - * by using gtk_info_bar_set_message_type(). GTK may use the message type - * to determine how the message is displayed. + * The API of `GtkInfoBar` is very similar to `GtkDialog`, allowing you + * to add buttons to the action area with [method@Gtk.InfoBar.add_button] + * or [ctor@Gtk.InfoBar.new_with_buttons]. The sensitivity of action widgets + * can be controlled with [method@Gtk.InfoBar.set_response_sensitive]. * - * A simple example for using a #GtkInfoBar: - * |[ + * To add widgets to the main content area of a `GtkInfoBar`, use + * [method@Gtk.InfoBar.add_child]. + * + * Similar to [class@Gtk.MessageDialog], the contents of a `GtkInfoBar` + * can by classified as error message, warning, informational message, etc, + * by using [method@Gtk.InfoBar.set_message_type]. GTK may use the message + * type to determine how the message is displayed. + * + * A simple example for using a `GtkInfoBar`: + * ```c * GtkWidget *message_label; * GtkWidget *widget; * GtkWidget *grid; @@ -103,22 +106,22 @@ * gtk_label_set_text (GTK_LABEL (message_label), "An error occurred!"); * gtk_info_bar_set_message_type (bar, GTK_MESSAGE_ERROR); * gtk_widget_show (bar); - * ]| + * ``` * * # GtkInfoBar as GtkBuildable * - * The GtkInfoBar implementation of the GtkBuildable interface exposes + * The `GtkInfoBar` implementation of the `GtkBuildable` interface exposes * the content area and action area as internal children with the names * “content_area” and “action_area”. * - * GtkInfoBar supports a custom element, which can contain + * `GtkInfoBar` supports a custom element, which can contain * multiple elements. The “response” attribute specifies a * numeric response, and the content of the element is the id of widget * (which should be a child of the dialogs @action_area). * * # CSS nodes * - * GtkInfoBar has a single CSS node with name infobar. The node may get + * `GtkInfoBar` has a single CSS node with name infobar. The node may get * one of the style classes .info, .warning, .error or .question, depending * on the message type. * If the info bar shows a close button, that button will have the .close @@ -372,6 +375,11 @@ gtk_info_bar_class_init (GtkInfoBarClass *klass) FALSE, GTK_PARAM_READWRITE|G_PARAM_CONSTRUCT|G_PARAM_EXPLICIT_NOTIFY); + /** + * GtkInfoBar:revealed: + * + * Whether the info bar shows its contents. + */ props[PROP_REVEALED] = g_param_spec_boolean ("revealed", P_("Reveal"), @@ -386,9 +394,11 @@ gtk_info_bar_class_init (GtkInfoBarClass *klass) * @info_bar: the object on which the signal is emitted * @response_id: the response ID * - * Emitted when an action widget is clicked or the application programmer - * calls gtk_info_bar_response(). The @response_id depends on which action - * widget was clicked. + * Emitted when an action widget is clicked. + * + * The signal is also emitted when the application programmer + * calls [method@Gtk.InfoBar.response]. The @response_id depends + * on which action widget was clicked. */ signals[RESPONSE] = g_signal_new (I_("response"), G_OBJECT_CLASS_TYPE (klass), @@ -402,10 +412,9 @@ gtk_info_bar_class_init (GtkInfoBarClass *klass) /** * GtkInfoBar::close: * - * The ::close signal is a - * [keybinding signal][GtkSignalAction] - * which gets emitted when the user uses a keybinding to dismiss - * the info bar. + * Gets emitted when the user uses a keybinding to dismiss the info bar. + * + * The ::close signal is a [keybinding signal](class.SignalAction.html). * * The default binding for this signal is the Escape key. */ @@ -523,14 +532,16 @@ action_widget_activated (GtkWidget *widget, /** * gtk_info_bar_add_action_widget: - * @info_bar: a #GtkInfoBar + * @info_bar: a `GtkInfoBar` * @child: an activatable widget * @response_id: response ID for @child * - * Add an activatable widget to the action area of a #GtkInfoBar, - * connecting a signal handler that will emit the #GtkInfoBar::response - * signal on the message area when the widget is activated. The widget - * is appended to the end of the message areas action area. + * Add an activatable widget to the action area of a `GtkInfoBar`. + * + * This also connects a signal handler that will emit the + * [signal@Gtk.InfoBar::response] signal on the message area + * when the widget is activated. The widget is appended to the + * end of the message areas action area. */ void gtk_info_bar_add_action_widget (GtkInfoBar *info_bar, @@ -569,12 +580,13 @@ gtk_info_bar_add_action_widget (GtkInfoBar *info_bar, /** * gtk_info_bar_remove_action_widget: - * @info_bar: a #GtkInfoBar + * @info_bar: a `GtkInfoBar` * @widget: an action widget to remove * - * Removes a widget from the action area of @info_bar, after - * it been put there by a call to gtk_info_bar_add_action_widget() - * or gtk_info_bar_add_button(). + * Removes a widget from the action area of @info_bar. + * + * The widget must have been put there by a call to + * [method@Gtk.InfoBar.add_action_widget] or [method@Gtk.InfoBar.add_button]. */ void gtk_info_bar_remove_action_widget (GtkInfoBar *info_bar, @@ -591,17 +603,18 @@ gtk_info_bar_remove_action_widget (GtkInfoBar *info_bar, /** * gtk_info_bar_add_button: - * @info_bar: a #GtkInfoBar + * @info_bar: a `GtkInfoBar` * @button_text: text of button * @response_id: response ID for the button * - * Adds a button with the given text and sets things up so that - * clicking the button will emit the “response” signal with the given - * response_id. The button is appended to the end of the info bars's - * action area. The button widget is returned, but usually you don't - * need it. + * Adds a button with the given text. * - * Returns: (transfer none) (type Gtk.Button): the #GtkButton widget + * Clicking the button will emit the [signal@Gtk.InfoBar::response] + * signal with the given response_id. The button is appended to the + * end of the info bars's action area. The button widget is returned, + * but usually you don't need it. + * + * Returns: (transfer none) (type Gtk.Button): the `GtkButton` widget * that was added */ GtkWidget* @@ -654,14 +667,16 @@ add_buttons_valist (GtkInfoBar *info_bar, /** * gtk_info_bar_add_buttons: - * @info_bar: a #GtkInfoBar + * @info_bar: a `GtkInfoBar` * @first_button_text: button text * @...: response ID for first button, then more text-response_id pairs, * ending with %NULL * - * Adds more buttons, same as calling gtk_info_bar_add_button() + * Adds multiple buttons. + * + * This is the same as calling [method@Gtk.InfoBar.add_button] * repeatedly. The variable argument list should be %NULL-terminated - * as with gtk_info_bar_new_with_buttons(). Each button must have both + * as with [ctor@Gtk.InfoBar.new_with_buttons]. Each button must have both * text and response ID. */ void @@ -679,9 +694,9 @@ gtk_info_bar_add_buttons (GtkInfoBar *info_bar, /** * gtk_info_bar_new: * - * Creates a new #GtkInfoBar object. + * Creates a new `GtkInfoBar` object. * - * Returns: a new #GtkInfoBar object + * Returns: a new `GtkInfoBar` object */ GtkWidget * gtk_info_bar_new (void) @@ -695,14 +710,16 @@ gtk_info_bar_new (void) * @...: response ID for first button, then additional buttons, ending * with %NULL * - * Creates a new #GtkInfoBar with buttons. Button text/response ID - * pairs should be listed, with a %NULL pointer ending the list. - * A response ID can be any positive number, - * or one of the values in the #GtkResponseType enumeration. If the + * Creates a new `GtkInfoBar` with buttons. + * + * Button text/response ID pairs should be listed, with a %NULL pointer + * ending the list. A response ID can be any positive number, + * or one of the values in the `GtkResponseType` enumeration. If the * user clicks one of these dialog buttons, GtkInfoBar will emit - * the “response” signal with the corresponding response ID. + * the [signal@Gtk.InfoBar::response] signal with the corresponding + * response ID. * - * Returns: a new #GtkInfoBar + * Returns: a new `GtkInfoBar` */ GtkWidget* gtk_info_bar_new_with_buttons (const char *first_button_text, @@ -736,13 +753,15 @@ update_default_response (GtkInfoBar *info_bar, /** * gtk_info_bar_set_response_sensitive: - * @info_bar: a #GtkInfoBar + * @info_bar: a `GtkInfoBar` * @response_id: a response ID * @setting: TRUE for sensitive * - * Calls gtk_widget_set_sensitive (widget, setting) for each - * widget in the info bars’s action area with the given response_id. - * A convenient way to sensitize/desensitize dialog buttons. + * Sets the sensitivity of action widgets for @response_id. + * + * Calls `gtk_widget_set_sensitive (widget, setting)` for each + * widget in the info bars’s action area with the given @response_id. + * A convenient way to sensitize/desensitize buttons. */ void gtk_info_bar_set_response_sensitive (GtkInfoBar *info_bar, @@ -769,15 +788,16 @@ gtk_info_bar_set_response_sensitive (GtkInfoBar *info_bar, /** * gtk_info_bar_set_default_response: - * @info_bar: a #GtkInfoBar + * @info_bar: a `GtkInfoBar` * @response_id: a response ID * * Sets the last widget in the info bar’s action area with * the given response_id as the default widget for the dialog. + * * Pressing “Enter” normally activates the default widget. * * Note that this function currently requires @info_bar to - * be added to a widget hierarchy. + * be added to a widget hierarchy. */ void gtk_info_bar_set_default_response (GtkInfoBar *info_bar, @@ -810,7 +830,7 @@ gtk_info_bar_set_default_response (GtkInfoBar *info_bar, /** * gtk_info_bar_response: - * @info_bar: a #GtkInfoBar + * @info_bar: a `GtkInfoBar` * @response_id: a response ID * * Emits the “response” signal with the given @response_id. @@ -1054,7 +1074,7 @@ gtk_info_bar_buildable_add_child (GtkBuildable *buildable, /** * gtk_info_bar_set_message_type: - * @info_bar: a #GtkInfoBar + * @info_bar: a `GtkInfoBar` * @message_type: a #GtkMessageType * * Sets the message type of the message area. @@ -1093,7 +1113,7 @@ gtk_info_bar_set_message_type (GtkInfoBar *info_bar, /** * gtk_info_bar_get_message_type: - * @info_bar: a #GtkInfoBar + * @info_bar: a `GtkInfoBar` * * Returns the message type of the message area. * @@ -1110,11 +1130,12 @@ gtk_info_bar_get_message_type (GtkInfoBar *info_bar) /** * gtk_info_bar_set_show_close_button: - * @info_bar: a #GtkInfoBar + * @info_bar: a `GtkInfoBar` * @setting: %TRUE to include a close button * - * If true, a standard close button is shown. When clicked it emits - * the response %GTK_RESPONSE_CLOSE. + * If true, a standard close button is shown. + * + * When clicked it emits the response %GTK_RESPONSE_CLOSE. */ void gtk_info_bar_set_show_close_button (GtkInfoBar *info_bar, @@ -1131,7 +1152,7 @@ gtk_info_bar_set_show_close_button (GtkInfoBar *info_bar, /** * gtk_info_bar_get_show_close_button: - * @info_bar: a #GtkInfoBar + * @info_bar: a `GtkInfoBar` * * Returns whether the widget will display a standard close button. * @@ -1147,14 +1168,17 @@ gtk_info_bar_get_show_close_button (GtkInfoBar *info_bar) /** * gtk_info_bar_set_revealed: - * @info_bar: a #GtkInfoBar + * @info_bar: a `GtkInfoBar` * @revealed: The new value of the property * - * Sets the #GtkInfoBar:revealed property to @revealed. Changing this will make - * @info_bar reveal (%TRUE) or conceal (%FALSE) itself via a sliding transition. + * Sets whether the `GtkInfoBar` is revealed. * - * Note: this does not show or hide @info_bar in the #GtkWidget:visible sense, - * so revealing has no effect if #GtkWidget:visible is %FALSE. + * Changing this will make @info_bar reveal or conceal + * itself via a sliding transition. + * + * Note: this does not show or hide @info_bar in the + * [property@Gtk.Widget:visible] sense, so revealing has no effect + * if [property@Gtk.Widget:visible] is %FALSE. */ void gtk_info_bar_set_revealed (GtkInfoBar *info_bar, @@ -1171,11 +1195,11 @@ gtk_info_bar_set_revealed (GtkInfoBar *info_bar, /** * gtk_info_bar_get_revealed: - * @info_bar: a #GtkInfoBar + * @info_bar: a `GtkInfoBar` * * Returns whether the info bar is currently revealed. * - * Returns: the current value of the #GtkInfoBar:revealed property + * Returns: the current value of the [property@Gtk.InfoBar:revealed] property */ gboolean gtk_info_bar_get_revealed (GtkInfoBar *info_bar) @@ -1187,7 +1211,7 @@ gtk_info_bar_get_revealed (GtkInfoBar *info_bar) /** * gtk_info_bar_add_child: - * @info_bar: a #GtkInfoBar + * @info_bar: a `GtkInfoBar` * @widget: the child to be added * * Adds a widget to the content area of the info bar. @@ -1204,11 +1228,10 @@ gtk_info_bar_add_child (GtkInfoBar *info_bar, /** * gtk_info_bar_remove_child: - * @info_bar: a #GtkInfoBar + * @info_bar: a `GtkInfoBar` * @widget: a child that has been added to the content area * - * Removes a widget from the content area of the info bar, - * after it has been added with gtk_info_bar_add_child(). + * Removes a widget from the content area of the info bar. */ void gtk_info_bar_remove_child (GtkInfoBar *info_bar, @@ -1219,4 +1242,3 @@ gtk_info_bar_remove_child (GtkInfoBar *info_bar, gtk_box_remove (GTK_BOX (info_bar->content_area), widget); } - -- 2.30.2